Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 5 - Using Macintosh Windows

Attaching a View Port to a Macintosh Window

This programming recipe discusses how you can create a Macintosh window, and a QuickDraw GX view port object, and attach the view port to the window.

Each QuickDraw GX shape references a transform object, which references one (or more) view port objects. When you draw a shape, QuickDraw GX uses the shape's view port object to decide where to render the shape. If you've attached the shape's view port to a Macintosh window, QuickDraw GX renders the shape into the window.

Figure 5-1 shows the relationship between a shape, its transform, and its
view port.

Figure 5-1 A shape drawn to a Macintosh window

This recipe associates a view port object with a Macintosh window. Then, when you draw shapes whose transform objects reference that view port object, QuickDraw GX renders the shape in the window.

When you attach a view port to a Macintosh window, QuickDraw GX
manages the mapping and clip properties of that view port for you so that these properties always reflect the current size and position of the view
port's window.

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Create a Macintosh window
2. Create a new view port object and attach it to the window
3. Set the new view port to be the default view port
4. Close the window

Some of the steps in this recipe are optional. For example, you don't have to set your view port to be the default view port. You do, however, have to attach the view port to the transform object of any QuickDraw GX shape that you want to draw to your window.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXNewWindowViewPort	"QuickDraw GX and the Macintosh Environment" QuickDraw GX Environment and Utilities
GXSetShapeViewPorts	"Transform Objects" QuickDraw GX Objects
GXDrawShape	"Shape Objects" QuickDraw GX Objects
GXDisposeViewPort	"View-Related Objects" QuickDraw GX Objects

Standard Macintosh functions used in this recipe:

GetNewCWindow	"Window Manager" Macintosh Toolbox Essentials
GetNewWindow	"Window Manager" Macintosh Toolbox Essentials
NewCWindow	"Window Manager" Macintosh Toolbox Essentials
NewWindow	"Window Manager" Macintosh Toolbox Essentials
BeginUpdate	"Window Manager" Macintosh Toolbox Essentials
EndUpdate	"Window Manager" Macintosh Toolbox Essentials
DisposeWindow	"Window Manager" Macintosh Toolbox Essentials

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

This recipe also uses a function from the QuickDraw GX libraries:

SetDefaultViewPort

transform library

Recipe Step Descriptions

In this section each step is described individually.

1. Create a Macintosh window

   You create a Macintosh window using the Macintosh Window Manager. Typically, you specify the characteristics of the window--such as its initial size, location, title, and so on--in a window resource and you call the GetNewCWindow or GetNewWindow function to create the window using the window resource. You can also create a window programmatically using the NewWindow or NewCWindow function. For example, you can create a window using this code:

   WindowPtr gWindow;

   Rect windowRect = {50, 50, 300, 300};

   gWindow = NewWindow(nil, &windowRect, "\pWindow Title",
                       true, documentProc, (WindowPtr) -1, 
                       true, 0L);

   The documentProc constant specifies a window with no zoom box and no resize box, which is what this recipe uses. The next recipe, "Resizing and Zooming a Window" on page 161, introduces windows that you can zoom and resize.

2. Create a new view port object and attach it to the window

   The window record created by the NewWindow function represents the window in the standard Macintosh world. To draw QuickDraw GX shapes into the window, you need to create a view port object and attach it to the window. QuickDraw GX provides the GXNewWindowViewPort function for exactly this purpose.

   gxViewPort gWindowViewPort;

   gWindowViewPort = GXNewWindowViewPort(gWindow);

   Once you've attached a view port object to a window with this function, QuickDraw GX manages the properties of the view port object for you. If the window is moved or resized, QuickDraw GX adjusts the mapping and clip properties of the view port to reflect the new size and location of the window when you call the BeginUpdate and EndUpdate standard Macintosh functions. That way, whenever you draw a QuickDraw shape to the view port, it's sure to appear in the right place in the window.

3. Set the new view port to be the default view port

   If you want to draw a QuickDraw GX shape into your window, you must make sure the view port list of the shape's transform object contains a reference to the view port attached to the window. You can use the GXSetShapeViewPorts function to change a shape's view port list. For example, if you have a shape reference stored in a variable named eachShape, you can set the view port list of the shape using this function call:

   GXSetShapeViewPorts(eachShape, 1, &gWindowViewPort);

   Once the shape's view port list references the window view port object,
   you simply draw the shape with the GXDrawShape function when you
   want QuickDraw GX to render the shape in the window:

   GXDrawShape(eachShape);

   Another way to attach your shapes to the window view port is to make the window view port be the default view port. The default view port is the view port that the default shapes initially reference in their view port lists. Remember that when you create a shape, QuickDraw GX makes a copy of the default shape of the specified type. If you make your window view port be the default view port, then each time you create a shape, the new shape automatically references the window view port in its view port list.

   You use the QuickDraw GX library function SetDefaultViewPort to make your window view port be the default view port:

   SetDefaultViewPort(gWindowViewPort);

   Now, whenever you draw a newly created shape, QuickDraw GX renders it in your window.

4. Close the window

   When the user closes your window, you should dispose of the appropriate shapes and then dispose of your window view port using the GXDisposeViewPort function and then dispose of your window using
   the standard Macintosh function DisposeWindow:

   GXDisposeViewPort(gWindowViewPort);

   DisposeWindow(gWindow);

Related Recipes

For more information related to using QuickDraw GX and Macintosh windows, see these recipes:

• "Resizing and Zooming a Window," described next, shows how to handle resize and zoom boxes in your windows.
• "Adding Scrolling to a Window," on page 169, shows how to implement scrolling using multiple view ports per window.

The recipes in the previous chapter, "Using the QuickDraw GX Environment," show you how to initialize QuickDraw GX and set up the QuickDraw GX debugging facilities. You should read the recipes in that chapter before using any recipes in this chapter.

The recipes in Chapter 6, "Handling Graphics," and in Chapter 7, "Handling Typography," show you how to create and manipulate images to draw into
a window.